~ chicken-core (chicken-5) /manual/Module (chicken file)
Trap1[[tags: manual]]2[[toc:]]34== Module (chicken file)56This module provides various generic operations on files and7directories. For more specific operations, see also8[[Module (chicken file posix)]].910All errors related to failing file-operations will signal a condition11of kind {{(exn i/o file)}}.1213* New in CHICKEN 5.4.0: Errors caused by underlying C calls that14 change errno will produce a condition object with an {{errno}}15 property, which can be accessed with16 {{(get-condition-property <the-condition-object> 'exn 'errno)}}.1718=== Basic file operations1920==== create-directory2122<procedure>(create-directory NAME #!optional PARENTS?)</procedure>2324Creates a directory with the pathname {{NAME}}. If the {{PARENTS?}} argument25is given and not false, any nonexistent parent directories are also created.2627Notice that if {{NAME}} exists, {{create-directory}} won't try to create it28and will return {{NAME}} (i.e., it won't raise an error when given a {{NAME}}29that already exists).3031==== copy-file3233<procedure>(copy-file ORIGFILE NEWFILE #!optional CLOBBER BLOCKSIZE)</procedure>3435Copies {{ORIGFILE}} (a string denoting some filename) to {{NEWFILE}},36{{BLOCKSIZE}} bytes at a time. {{BLOCKSIZE}} defaults to 1024, and37must be a positive integer. Returns the number of bytes copied on38success, or errors on failure. {{CLOBBER}} determines the behaviour39of {{copy-file}} when {{NEWFILE}} is already extant. When set to40{{#f}} (default), an error is signaled. When set to any other value,41{{NEWFILE}} is overwritten. {{copy-file}} will work across42filesystems and devices and is not platform-dependent.4344==== move-file4546<procedure>(move-file ORIGFILE NEWFILE #!optional CLOBBER BLOCKSIZE)</procedure>4748Moves {{ORIGFILE}} (a string denoting some filename) to {{NEWFILE}},49with the same semantics as {{copy-file}}, above. {{move-file}} is50safe across filesystems and devices (unlike {{rename-file}}). It is51possible for an error to be signaled despite partial success if52{{NEWFILE}} could be created and fully written but removing53{{ORIGFILE}} fails.5455If {{CLOBBER}} is given and not {{#f}}, {{NEWFILE}} will be replaced56when it already exists, otherwise an error is signaled.5758The {{BLOCKSIZE}} argument indicates the block size to use when59copying the file a block at a time. It must be a positive integer,60and it defaults to 1024.6162==== delete-file6364<procedure>(delete-file STRING)</procedure>6566Deletes the file with the pathname {{STRING}}. If the file does67not exist, an error is signaled.6869==== delete-file*7071<procedure>(delete-file* STRING)</procedure>7273If the file with pathname {{STRING}} exists, it is deleted and {{#t}}74is returned. If the file does not exist, nothing happens and {{#f}}75is returned.7677==== delete-directory7879<procedure>(delete-directory NAME [RECURSIVE])</procedure>8081Deletes the directory with the pathname {{NAME}}. If {{RECURSIVE}} is82not given or false, then the directory has to be empty.8384==== directory8586<procedure>(directory [PATHNAME [SHOW-DOTFILES?]])</procedure>8788Returns a list with all files that are contained in the directory with the name {{PATHNAME}}89(which defaults to the value of {{(current-directory)}}).90Files beginning with {{.}} are included only if {{SHOW-DOTFILES?}} is given and not {{#f}}.9192==== directory-exists?9394<procedure>(directory-exists? STRING)</procedure>9596Returns {{STRING}} if a directory with the given pathname exists, or97{{#f}} otherwise.9899100==== file-exists?101102<procedure>(file-exists? STRING)</procedure>103104Returns {{STRING}} if a file or directory with the given pathname exists, or105{{#f}} otherwise.106107108==== rename-file109110<procedure>(rename-file OLD NEW #!optional CLOBBER)</procedure>111112Renames the file or directory with the pathname {{OLD}} to113{{NEW}}. If the operation does not succeed, an error is signaled.114115If {{CLOBBER}} is given and not {{#f}}, {{NEW}} will be replaced when116it already exists, otherwise an error is signaled.117118==== file-readable?119==== file-writable?120==== file-executable?121122<procedure>(file-readable? FILENAME)</procedure><br>123<procedure>(file-writable? FILENAME)</procedure><br>124<procedure>(file-executable? FILENAME)</procedure>125126These procedures return {{#t}} if the current user has read,127write or execute permissions on the file named {{FILENAME}}.128129130=== Temporary files and directories131132==== create-temporary-file133134<procedure>(create-temporary-file [EXTENSION])</procedure>135136Creates an empty temporary file and returns its pathname. If137{{EXTENSION}} is not given, then {{.tmp}} is used. If the environment138variable {{TMPDIR}}, {{TEMP}} or {{TMP}} is set, then the pathname139names a file in that directory. If none of the environment variables140is given, the location of the temporary file defaults to {{/tmp}}.141142Note that {{TMPDIR}}, {{TEMP}} and {{TMP}} are checked in this order.143It means that, for example, if both {{TMPDIR}} and {{TEMP}} are set,144the value of {{TMPDIR}} will be used.145146Changed in CHICKEN 5.4.0: the values of the {{TMPDIR}}, {{TEMP}} and147{{TMP}} environment variables are no longer memoized (see148[[#1830|https://bugs.call-cc.org/ticket/1830]]).149150==== create-temporary-directory151152<procedure>(create-temporary-directory)</procedure>153154Creates an empty temporary directory and returns its pathname. If the155environment variable {{TMPDIR}}, {{TEMP}} or {{TMP}} is set, then the156temporary directory is created at that location. If none of the157environment variables is given, the location of the temporary158directory defaults to {{/tmp}}.159160Note that {{TMPDIR}}, {{TEMP}} and {{TMP}} are checked in this order.161It means that, for example, if both {{TMPDIR}} and {{TEMP}} are set,162the value of {{TMPDIR}} will be used.163164Changed in CHICKEN 5.4.0: the values of the {{TMPDIR}}, {{TEMP}} and165{{TMP}} environment variables are no longer memoized (see166[[#1830|https://bugs.call-cc.org/ticket/1830]]).167168=== Finding files169170==== find-files171172<procedure>(find-files DIRECTORY #!key test action seed limit dotfiles follow-symlinks)</procedure>173174Recursively traverses the contents of {{DIRECTORY}} (which should be a175string) and invokes the procedure {{action}} for all files in which176the procedure {{test}} is true.177178{{test}} may be a procedure of one argument or an irregex object,179regex string or SRE expression that will be matched with a full180pathname using {{irregex-match}}. {{test}} defaults to {{(constantly181#t)}}.182183184{{action}} should be a procedure of two arguments: the currently185encountered file and the result of the previous invocation of186{{action}}, or, if this is the first invocation, the value of187{{seed}}. {{action}} defaults to {{cons}}, {{seed}} defaults to {{()}}.188189{{limit}} should be a procedure of one argument that is called for190each nested directory and which should return true, if that directory191is to be traversed recursively. {{limit}} may also be an exact integer192that gives the maximum recursion depth. For example, a depth of {{0}}193means that only files in the top-level, specified directory are to be194traversed. In this case, all nested directories are ignored.195{{limit}} may also be {{#f}} (the default), which is equivalent to196{{(constantly #t)}}.197198If {{dotfiles}} is given and true, then files starting with a "{{.}}"199character will not be ignored (but note that "{{.}}" and "{{..}}" are200always ignored). if {{follow-symlinks}} is given and true, then the201traversal of a symbolic link that points to a directory will202recursively traverse the latter. By default, symbolic links are not203followed.204205Note that {{action}} is called with the full pathname of each file,206including the directory prefix.207208209==== glob210211<procedure>(glob PATTERN1 ...)</procedure>212213Returns a list of the pathnames of all existing files matching214{{PATTERN1 ...}}, which should be strings containing the usual215file-patterns (with {{*}} matching zero or more characters and216{{?}} matching zero or one character).217218---219Previous: [[Module (chicken eval)]]220221Next: [[Module (chicken file posix)]]